@brett_lamy/docstream-editor 0.7.0 → 1.0.0

package/README.md

@@ -75,6 +75,11 @@ export interface GitbookEditorProps {
   onChange: (markdown: string) => void
   onKeyDown?: (event: KeyboardEvent) => boolean
   onPaste?: (event: ClipboardEvent) => boolean
+  imagePaste?: "inline" | "chip"
+  attachments?: EditorAttachment[]
+  onAttachmentAdd?: (attachment: EditorAttachment & { file: File }) => void
+  onAttachmentRemove?: (ids: string[]) => void
+  onAttachmentOpen?: (attachment: EditorAttachment) => void
 }
 ```
 
@@ -82,6 +87,8 @@ export interface GitbookEditorProps {
 - `onChange`: Called with serialized markdown whenever TipTap content changes.
 - `onKeyDown` / `onPaste`: Optional host hooks that run before the built-in editor behavior;
   return `true` when the application handled the event.
+- `imagePaste`, `attachments`, `onAttachmentAdd`, `onAttachmentRemove`, `onAttachmentOpen`:
+  how pasted/dropped images are handled — see [Pasted and dropped images](#pasted-and-dropped-images).
 
 The editor tracks the last markdown it emitted so normal controlled updates do not continuously reset the TipTap document. Passing a different external `markdown` value replaces the editor content.
 
@@ -132,6 +139,42 @@ dollar signs in ordinary prose never open a menu. Free-form entry is always offe
 />
 ```
 
+## Pasted and dropped images
+
+`imagePaste` controls how pasted or dropped image files enter the document. It runs after
+your `onPaste` (return `true` there to take over). Clipboard data that also carries plain
+text, such as a Word or Excel selection, still pastes as text.
+
+- `"inline"` (default): an image block with the file as a data URL, the way it will render.
+- `"chip"`: a compact attachment chip at the caret. The host stores the file. The chip
+  serializes as `![image.png](attachment:att-xyz)`, shows a thumbnail and size, previews the
+  full image on hover, and opens it on click.
+
+```tsx
+const [markdown, setMarkdown] = useState("")
+const [attachments, setAttachments] = useState<EditorAttachment[]>([])
+
+<GitbookEditor
+  markdown={markdown}
+  onChange={setMarkdown}
+  imagePaste="chip"
+  attachments={attachments}
+  // once per image: { id, name, src (data URL), size, type, file }
+  onAttachmentAdd={({ file, ...attachment }) => setAttachments((all) => [...all, attachment])}
+  // chips deleted, cut or cleared by the user
+  onAttachmentRemove={(ids) => setAttachments((all) => all.filter((a) => !ids.includes(a.id)))}
+  // optional; omit it to use the built-in full-screen viewer
+  onAttachmentOpen={(attachment) => openLightbox(attachment)}
+/>
+```
+
+`EditorAttachment` is `{ id, name, src?, size?, type? }`. Chips find their image in
+`attachments` by id, so `src` can be a data URL or an uploaded URL. To remove a chip
+from outside the editor, call `editor.commands.removeAttachment(id)` (get the instance
+from `onEditorReady`). Markdown images with an `attachment:` URL always load as chips,
+whatever the mode. `serializeEditorMarkdown(ast)` is the serializer that writes them in
+this form.
+
 ## Edit a referenced source file
 
 `GitbookEditor` edits the Markdown composition, including a structured
@@ -182,6 +225,8 @@ Exports:
 - `astToTiptap`
 - `tiptapToAst`
 - `PMNode`
+- `EditorAttachment`
+- `serializeEditorMarkdown`
 - `SourceFileEditor`
 - `SourceFileEditorProps`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brett_lamy/docstream-editor",
-  "version": "0.7.0",
+  "version": "1.0.0",
   "description": "TipTap editor for Docstream GitBook-style markdown documents.",
   "type": "module",
   "scripts": {
@@ -33,7 +33,7 @@
     "./styles.css": "./src/styles.css"
   },
   "dependencies": {
-    "@brett_lamy/docstream": "0.6.0",
+    "@brett_lamy/docstream": "1.0.0",
     "gpu-lexer": "0.0.2",
     "lucide-react": "^1.17.0"
   },

package/src/editor/Editor.tsx

@@ -10,13 +10,23 @@ import {
   Strikethrough,
 } from "lucide-react"
 
-import { parseMarkdown, serializeMarkdown, type CitationDef } from "@brett_lamy/docstream/gitbook"
+import { parseMarkdown, type CitationDef } from "@brett_lamy/docstream/gitbook"
 import type { SourceFileSnapshot, SourceReferenceClient } from "@brett_lamy/docstream/source"
-import { astToTiptap, tiptapToAst, type PMNode } from "./convert"
+import {
+  attachmentName,
+  collectAttachmentIds,
+  imageFilesFrom,
+  newAttachmentId,
+  readFileAsDataURL,
+  type EditorAttachment,
+} from "./attachments"
+import { astToTiptap, serializeEditorMarkdown, tiptapToAst, type PMNode } from "./convert"
 import { createGitbookExtensions, type ReferenceSources } from "./extensions"
 import { EditorRuntimeProvider } from "./runtime"
 import type { SlashItem } from "./slash-menu"
 
+export type { EditorAttachment } from "./attachments"
+
 export interface GitbookEditorProps {
   /** Markdown source. When provided, the editor stays in sync with it (controlled). */
   markdown?: string
@@ -50,6 +60,20 @@ export interface GitbookEditorProps {
   onKeyDown?: (event: KeyboardEvent) => boolean
   /** Handle clipboard content before the editor's built-in paste behavior. Return true when handled. */
   onPaste?: (event: ClipboardEvent) => boolean
+  /**
+   * How pasted or dropped image files enter the document.
+   * "inline" (default) — an image block with the file as a data URL, as it will render.
+   * "chip" — a compact attachment chip at the caret; the host owns the file via `attachments`.
+   */
+  imagePaste?: "inline" | "chip"
+  /** Chip mode: the host's attachment store. Chips look up their thumbnail, full image and size here by id. */
+  attachments?: EditorAttachment[]
+  /** Chip mode: fired once per pasted/dropped image with a fresh id and the file read as a data URL. Add it to `attachments`. */
+  onAttachmentAdd?: (attachment: EditorAttachment & { file: File }) => void
+  /** Chip mode: fired when chips disappear from the document (deleted, cut, cleared) with their ids. */
+  onAttachmentRemove?: (ids: string[]) => void
+  /** Chip mode: clicking (or Enter/Space on a focused) chip. Omit to open the built-in image viewer. */
+  onAttachmentOpen?: (attachment: EditorAttachment) => void
   /** Receive the underlying TipTap editor instance (and null on teardown). */
   onEditorReady?: (editor: TiptapEditor | null) => void
   /** Client used to edit and preview `{% source-ref %}` files. */
@@ -138,6 +162,11 @@ export function GitbookEditor({
   extensions,
   onKeyDown,
   onPaste,
+  imagePaste = "inline",
+  attachments,
+  onAttachmentAdd,
+  onAttachmentRemove,
+  onAttachmentOpen,
   onEditorReady,
   sourceClient,
   sourcePreview = true,
@@ -152,6 +181,56 @@ export function GitbookEditor({
   // ones from the last applied markdown and reattach them on serialize.
   const citationsRef = useRef<CitationDef[] | undefined>(undefined)
   const controlled = markdown !== undefined
+  // Ids of the attachment chips in the document, to report removals.
+  const attachmentIds = useRef<Set<string>>(new Set())
+  // Latest callbacks for handlers the editor captured at creation.
+  const latest = useRef({ onPaste, imagePaste, onAttachmentAdd, onAttachmentRemove })
+  latest.current = { onPaste, imagePaste, onAttachmentAdd, onAttachmentRemove }
+  const editorRef = useRef<TiptapEditor | null>(null)
+
+  // Pasted/dropped image files: image blocks ("inline") or attachment chips ("chip").
+  const insertImageFiles = (files: File[], at?: number) => {
+    const ed = editorRef.current
+    if (!ed) return
+    const insert = (content: PMNode[]) => {
+      const chain = ed.chain().focus()
+      const pos = at === undefined ? undefined : Math.min(at, ed.state.doc.content.size)
+      ;(pos === undefined ? chain.insertContent(content) : chain.insertContentAt(pos, content)).run()
+    }
+    if (latest.current.imagePaste === "chip") {
+      const items = files.map((file) => ({ file, id: newAttachmentId(), name: attachmentName(file) }))
+      // Keep chips off the preceding word: "done.[chip]" → "done. [chip]".
+      const $at = at === undefined ? ed.state.selection.$from : ed.state.doc.resolve(Math.min(at, ed.state.doc.content.size))
+      const before = $at.parent.isTextblock ? $at.parent.textBetween(Math.max(0, $at.parentOffset - 1), $at.parentOffset, "", "\uFFFC") : ""
+      const lead: PMNode[] = before && !/\s/.test(before) ? [{ type: "text", text: " " }] : []
+      insert([
+        ...lead,
+        ...items.flatMap(({ id, name }): PMNode[] => [
+          { type: "gbAttachment", attrs: { id, name } },
+          { type: "text", text: " " },
+        ]),
+      ])
+      for (const { file, id, name } of items) {
+        const base = { id, name, size: file.size, type: file.type, file }
+        readFileAsDataURL(file).then(
+          (src) => latest.current.onAttachmentAdd?.({ ...base, src }),
+          () => latest.current.onAttachmentAdd?.(base)
+        )
+      }
+      return
+    }
+    void Promise.all(
+      files.map((file) =>
+        readFileAsDataURL(file).then(
+          (src): PMNode => ({ type: "gbFigure", attrs: { src, alt: attachmentName(file), caption: "" } }),
+          () => null
+        )
+      )
+    ).then((figures) => {
+      const content = figures.filter((f): f is PMNode => f !== null)
+      if (content.length && !ed.isDestroyed) insert(content)
+    })
+  }
 
   const parseAndTrack = (md: string) => {
     const doc = parseMarkdown(md)
@@ -171,19 +250,44 @@ export function GitbookEditor({
     }),
     editorProps: {
       handleKeyDown: (_view, event) => onKeyDown?.(event) ?? false,
-      handlePaste: (_view, event) => onPaste?.(event) ?? false,
+      handlePaste: (view, event) => {
+        if (latest.current.onPaste?.(event)) return true
+        if (!view.editable || view.state.selection.$from.parent.type.spec.code) return false
+        const files = imageFilesFrom(event.clipboardData, { ignoreWithText: true })
+        if (!files.length) return false
+        event.preventDefault()
+        insertImageFiles(files)
+        return true
+      },
+      handleDrop: (view, event, _slice, moved) => {
+        if (moved || !view.editable) return false
+        const files = imageFilesFrom(event.dataTransfer)
+        if (!files.length) return false
+        event.preventDefault()
+        insertImageFiles(files, view.posAtCoords({ left: event.clientX, top: event.clientY })?.pos)
+        return true
+      },
     },
     ...(controlled ? { content: astToTiptap(parseAndTrack(markdown as string)) } : {}),
+    onCreate({ editor }) {
+      attachmentIds.current = collectAttachmentIds(editor.state.doc)
+    },
     onUpdate({ editor }) {
+      const ids = collectAttachmentIds(editor.state.doc)
+      const removed = [...attachmentIds.current].filter((id) => !ids.has(id))
+      attachmentIds.current = ids
+      if (removed.length) latest.current.onAttachmentRemove?.(removed)
       if (!onChange) return
       const ast = tiptapToAst(editor.getJSON() as PMNode)
       if (citationsRef.current?.length) ast.citations = citationsRef.current
-      const md = serializeMarkdown(ast)
+      const md = serializeEditorMarkdown(ast)
       lastEmitted.current = md
       onChange(md)
     },
   })
 
+  editorRef.current = editor ?? null
+
   // Surface the editor instance to the host (for awareness, commands, etc.).
   useEffect(() => {
     onEditorReady?.(editor ?? null)
@@ -197,6 +301,8 @@ export function GitbookEditor({
     const doc = parseMarkdown(markdown as string)
     citationsRef.current = doc.citations
     editor.commands.setContent(astToTiptap(doc), { emitUpdate: false })
+    // Chips replaced by the host's own markdown aren't "removed" by the user.
+    attachmentIds.current = collectAttachmentIds(editor.state.doc)
   }, [editor, controlled, markdown])
 
   const runtime = useMemo(() => ({
@@ -205,7 +311,9 @@ export function GitbookEditor({
     sourceAutoSave,
     ...(onSourceSaved ? { onSourceSaved } : {}),
     ...(onSourceError ? { onSourceError } : {}),
-  }), [onSourceError, onSourceSaved, sourceAutoSave, sourceClient, sourcePreview])
+    ...(attachments ? { attachments } : {}),
+    ...(onAttachmentOpen ? { onAttachmentOpen } : {}),
+  }), [attachments, onAttachmentOpen, onSourceError, onSourceSaved, sourceAutoSave, sourceClient, sourcePreview])
 
   if (!editor) return null
 

package/src/editor/attachments.tsx

@@ -0,0 +1,354 @@
+import { Node, mergeAttributes } from "@tiptap/core"
+import type { Node as ProseMirrorNode } from "@tiptap/pm/model"
+import { NodeViewWrapper, ReactNodeViewRenderer, type NodeViewProps } from "@tiptap/react"
+import { ImageIcon } from "lucide-react"
+import { useCallback, useEffect, useLayoutEffect, useRef, useState, type CSSProperties } from "react"
+import { createPortal } from "react-dom"
+
+import { useEditorRuntime } from "./runtime"
+
+/** A file the host owns, referenced from the document by an attachment chip. */
+export interface EditorAttachment {
+  id: string
+  name: string
+  /** Full image URL (typically a data URL). Also used for the chip thumbnail. */
+  src?: string
+  /** Size in bytes. */
+  size?: number
+  /** MIME type. */
+  type?: string
+}
+
+/** The URL scheme attachment chips serialize to: `![name](attachment:<id>)`. */
+export const ATTACHMENT_SCHEME = "attachment:"
+
+export function newAttachmentId(): string {
+  const rand =
+    typeof crypto !== "undefined" && "randomUUID" in crypto
+      ? crypto.randomUUID().replace(/-/g, "").slice(0, 12)
+      : Math.random().toString(36).slice(2, 14)
+  return `att-${rand}`
+}
+
+/**
+ * The name a pasted/dropped file gets in the document. Clipboard screenshots
+ * usually arrive as "image.png"; unnamed ones get that too. Characters that
+ * would break `![alt](src)` / `alt="…"` are replaced.
+ */
+export function attachmentName(file: File): string {
+  const name = (file.name || "image.png").replace(/[[\]"<>\r\n]/g, "_").trim()
+  return name || "image.png"
+}
+
+/** "84 KB", "1.3 MB". */
+export function formatBytes(bytes: number | undefined): string {
+  if (bytes === undefined || !Number.isFinite(bytes) || bytes < 0) return ""
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`
+  if (bytes < 1024 * 1024 * 1024) return `${(bytes / (1024 * 1024)).toFixed(1)} MB`
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`
+}
+
+export function readFileAsDataURL(file: File): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader()
+    reader.onload = () => resolve(String(reader.result ?? ""))
+    reader.onerror = () => reject(reader.error ?? new Error(`Could not read ${file.name}`))
+    reader.readAsDataURL(file)
+  })
+}
+
+/**
+ * Image files carried by a paste or drop. Clipboard data that also has plain
+ * text (e.g. a Word/Excel selection, which ships a rendered PNG alongside the
+ * text) is left to the normal text paste.
+ */
+export function imageFilesFrom(data: DataTransfer | null, { ignoreWithText = false } = {}): File[] {
+  if (!data) return []
+  const files = Array.from(data.files ?? []).filter((f) => f.type.startsWith("image/"))
+  if (!files.length) return []
+  if (ignoreWithText && data.getData("text/plain").trim()) return []
+  return files
+}
+
+/** Ids of every attachment chip in a document. */
+export function collectAttachmentIds(doc: ProseMirrorNode): Set<string> {
+  const ids = new Set<string>()
+  doc.descendants((node) => {
+    if (node.type.name === "gbAttachment" && node.attrs.id) ids.add(String(node.attrs.id))
+    return node.isBlock || node.type.name === "doc"
+  })
+  return ids
+}
+
+// ---------- Hover card ----------
+
+const HOVER_DELAY = 150
+const HIDE_GRACE = 120
+const GAP = 8
+const MARGIN = 8
+
+function AttachmentHoverCard({
+  anchor,
+  attachment,
+}: {
+  anchor: HTMLElement
+  attachment: EditorAttachment
+}) {
+  const cardRef = useRef<HTMLDivElement>(null)
+  const [pos, setPos] = useState<{ top: number; left: number } | null>(null)
+
+  const place = useCallback(() => {
+    const card = cardRef.current
+    if (!card) return
+    const a = anchor.getBoundingClientRect()
+    const { width, height } = card.getBoundingClientRect()
+    const vw = window.innerWidth
+    const vh = window.innerHeight
+    let top = a.top - GAP - height
+    if (top < MARGIN && a.bottom + GAP + height <= vh - MARGIN) top = a.bottom + GAP
+    top = Math.max(MARGIN, top)
+    const left = Math.min(Math.max(MARGIN, a.left + a.width / 2 - width / 2), Math.max(MARGIN, vw - MARGIN - width))
+    setPos({ top, left })
+  }, [anchor])
+
+  useLayoutEffect(place, [place, attachment.src])
+
+  const size = formatBytes(attachment.size)
+  const style: CSSProperties = pos
+    ? { top: pos.top, left: pos.left }
+    : { top: 0, left: 0, visibility: "hidden" }
+  return createPortal(
+    <div ref={cardRef} className="gb-attachment-card" style={style} role="tooltip">
+      {attachment.src ? (
+        <img className="gb-attachment-card-img" src={attachment.src} alt={attachment.name} onLoad={place} />
+      ) : (
+        <div className="gb-attachment-card-empty">
+          <ImageIcon className="size-5" />
+        </div>
+      )}
+      <div className="gb-attachment-card-meta">
+        <span className="gb-attachment-card-name">{attachment.name}</span>
+        {size && <span className="gb-attachment-card-size"> · {size}</span>}
+      </div>
+    </div>,
+    document.body
+  )
+}
+
+// ---------- Built-in viewer ----------
+
+function AttachmentViewer({ attachment, onClose }: { attachment: EditorAttachment; onClose: () => void }) {
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        e.preventDefault()
+        e.stopPropagation()
+        onClose()
+      }
+    }
+    document.addEventListener("keydown", onKey, true)
+    return () => document.removeEventListener("keydown", onKey, true)
+  }, [onClose])
+
+  return createPortal(
+    <div
+      className="gb-attachment-viewer"
+      role="dialog"
+      aria-modal="true"
+      aria-label={attachment.name}
+      onMouseDown={(e) => e.preventDefault()}
+      onClick={onClose}
+    >
+      {attachment.src ? (
+        <img className="gb-attachment-viewer-img" src={attachment.src} alt={attachment.name} />
+      ) : (
+        <div className="gb-attachment-viewer-empty">
+          <ImageIcon className="size-6" />
+          {attachment.name}
+        </div>
+      )}
+    </div>,
+    document.body
+  )
+}
+
+// ---------- Chip ----------
+
+function AttachmentView({ node, selected, editor }: NodeViewProps) {
+  const { attachments, onAttachmentOpen } = useEditorRuntime()
+  const id = String(node.attrs.id ?? "")
+  const stored = attachments?.find((a) => a.id === id)
+  const attachment: EditorAttachment = { ...stored, id, name: stored?.name || String(node.attrs.name || "image") }
+  const size = formatBytes(attachment.size)
+
+  const chipRef = useRef<HTMLSpanElement>(null)
+  const [hovered, setHovered] = useState(false)
+  const [focused, setFocused] = useState(false)
+  const [dismissed, setDismissed] = useState(false)
+  const [viewing, setViewing] = useState(false)
+  const showTimer = useRef<number | undefined>(undefined)
+  const hideTimer = useRef<number | undefined>(undefined)
+
+  const clearTimers = () => {
+    window.clearTimeout(showTimer.current)
+    window.clearTimeout(hideTimer.current)
+  }
+  useEffect(() => clearTimers, [])
+
+  // A fresh selection of the chip re-arms a card dismissed with Escape.
+  useEffect(() => {
+    if (selected) setDismissed(false)
+  }, [selected])
+
+  const cardOpen =
+    !viewing && !dismissed && (hovered || focused || (selected && editor.isFocused))
+
+  useEffect(() => {
+    if (!cardOpen) return
+    const hide = () => {
+      clearTimers()
+      setHovered(false)
+      setDismissed(true)
+    }
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") hide()
+    }
+    window.addEventListener("scroll", hide, true)
+    document.addEventListener("keydown", onKey, true)
+    return () => {
+      window.removeEventListener("scroll", hide, true)
+      document.removeEventListener("keydown", onKey, true)
+    }
+  }, [cardOpen])
+
+  const open = () => {
+    clearTimers()
+    setHovered(false)
+    if (onAttachmentOpen) onAttachmentOpen(attachment)
+    else setViewing(true)
+  }
+
+  const closeViewer = useCallback(() => setViewing(false), [])
+
+  return (
+    <NodeViewWrapper as="span" className="gb-attachment-wrap" contentEditable={false}>
+      <span
+        ref={chipRef}
+        className="gb-attachment"
+        role="button"
+        tabIndex={0}
+        aria-label={size ? `${attachment.name}, ${size}` : attachment.name}
+        data-attachment-id={id}
+        onMouseEnter={() => {
+          window.clearTimeout(hideTimer.current)
+          setDismissed(false)
+          showTimer.current = window.setTimeout(() => setHovered(true), HOVER_DELAY)
+        }}
+        onMouseLeave={() => {
+          window.clearTimeout(showTimer.current)
+          hideTimer.current = window.setTimeout(() => setHovered(false), HIDE_GRACE)
+        }}
+        onFocus={() => {
+          setDismissed(false)
+          setFocused(true)
+        }}
+        onBlur={() => setFocused(false)}
+        // Keep the caret where it is — the chip is a button, not a text target.
+        onMouseDown={(e) => e.preventDefault()}
+        onClick={(e) => {
+          e.preventDefault()
+          open()
+        }}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault()
+            e.stopPropagation()
+            open()
+          }
+        }}
+      >
+        <span className="gb-attachment-thumb">
+          {attachment.src ? (
+            <img src={attachment.src} alt="" draggable={false} />
+          ) : (
+            <ImageIcon className="gb-attachment-thumb-icon" />
+          )}
+        </span>
+        <span className="gb-attachment-name">{attachment.name}</span>
+        {size && <span className="gb-attachment-size">{size}</span>}
+      </span>
+      {cardOpen && chipRef.current && <AttachmentHoverCard anchor={chipRef.current} attachment={attachment} />}
+      {viewing && <AttachmentViewer attachment={attachment} onClose={closeViewer} />}
+    </NodeViewWrapper>
+  )
+}
+
+declare module "@tiptap/core" {
+  interface Commands<ReturnType> {
+    gbAttachment: {
+      /** Delete every attachment chip with this id. */
+      removeAttachment: (id: string) => ReturnType
+    }
+  }
+}
+
+/**
+ * Inline attachment chip (`![name](attachment:<id>)`). The file itself lives in
+ * the host's attachment store; the node only carries the id and display name.
+ */
+export const GbAttachment = Node.create({
+  name: "gbAttachment",
+  group: "inline",
+  inline: true,
+  atom: true,
+  selectable: true,
+  draggable: false,
+  addAttributes() {
+    return {
+      id: { default: "" },
+      name: { default: "" },
+    }
+  },
+  parseHTML() {
+    return [
+      {
+        tag: "span[data-gb-attachment]",
+        getAttrs: (el) => ({
+          id: (el as HTMLElement).getAttribute("data-gb-attachment") ?? "",
+          name: (el as HTMLElement).getAttribute("data-name") ?? "",
+        }),
+      },
+    ]
+  },
+  renderHTML({ HTMLAttributes, node }) {
+    return [
+      "span",
+      mergeAttributes(HTMLAttributes, { "data-gb-attachment": node.attrs.id, "data-name": node.attrs.name }),
+      String(node.attrs.name),
+    ]
+  },
+  renderText({ node }) {
+    return String(node.attrs.name)
+  },
+  addCommands() {
+    return {
+      removeAttachment:
+        (id) =>
+        ({ tr, state, dispatch }) => {
+          const ranges: Array<[number, number]> = []
+          state.doc.descendants((node, pos) => {
+            if (node.type.name === this.name && node.attrs.id === id) ranges.push([pos, pos + node.nodeSize])
+          })
+          if (!ranges.length) return false
+          if (dispatch) {
+            for (const [from, to] of ranges.reverse()) tr.delete(from, to)
+          }
+          return true
+        },
+    }
+  },
+  addNodeView() {
+    return ReactNodeViewRenderer(AttachmentView)
+  },
+})

package/src/editor/convert.ts

@@ -1,4 +1,19 @@
-import { plainText, type Block, type DocumentNode, type Inline, type ListItemNode } from "@brett_lamy/docstream/gitbook"
+import {
+  plainText,
+  serializeMarkdown,
+  type Block,
+  type DocumentNode,
+  type Inline,
+  type ListItemNode,
+} from "@brett_lamy/docstream/gitbook"
+
+// Attachment chips live in markdown as images with an `attachment:<id>` URL.
+const ATTACHMENT_SCHEME = "attachment:"
+const isAttachmentSrc = (src: string | undefined) => !!src && src.startsWith(ATTACHMENT_SCHEME)
+const attachmentPM = (src: string, alt: string | undefined): PMNode => ({
+  type: "gbAttachment",
+  attrs: { id: src.slice(ATTACHMENT_SCHEME.length), name: alt ?? "" },
+})
 
 // TipTap/ProseMirror JSON shape (loosely typed on purpose)
 export interface PMNode {
@@ -23,6 +38,7 @@ function inlineToPM(nodes: Inline[]): PMNode[] {
           attrs: { kind: n.kind, id: n.id, url: n.url ?? "", label: n.label ?? "" },
         }
       }
+      if (n.type === "image" && isAttachmentSrc(n.src)) return attachmentPM(n.src, n.alt)
       if (n.type === "image") {
         return {
           type: "gbInlineImage",
@@ -135,6 +151,8 @@ function blockToPM(b: Block): PMNode {
         content: b.columns.map((c) => ({ type: "gbColumn", content: blocksPM(c.children) })),
       }
     case "figure":
+      // A chip alone on its line parses as a figure; it is still a chip.
+      if (isAttachmentSrc(b.src)) return { type: "paragraph", content: [attachmentPM(b.src, b.alt)] }
       return { type: "gbFigure", attrs: { src: b.src, alt: b.alt, caption: b.caption } }
     case "list":
       return {
@@ -199,8 +217,22 @@ export function astToTiptap(doc: DocumentNode): PMNode {
 function pmTextToInline(nodes: PMNode[] | undefined): Inline[] {
   if (!nodes) return []
   return nodes
-    .filter((n) => (n.type === "text" && n.text) || n.type === "gbInlineImage" || n.type === "gbReference")
+    .filter(
+      (n) =>
+        (n.type === "text" && n.text) ||
+        n.type === "gbInlineImage" ||
+        n.type === "gbReference" ||
+        n.type === "gbAttachment"
+    )
     .map((n): Inline => {
+      if (n.type === "gbAttachment") {
+        const a = n.attrs ?? {}
+        return {
+          type: "image",
+          src: `${ATTACHMENT_SCHEME}${String(a.id ?? "")}`,
+          ...(a.name ? { alt: String(a.name) } : {}),
+        }
+      }
       if (n.type === "gbReference") {
         const a = n.attrs ?? {}
         const kind =
@@ -398,3 +430,19 @@ function pmToBlocks(nodes: PMNode[] | undefined): Block[] {
 export function tiptapToAst(doc: PMNode): DocumentNode {
   return { type: "doc", children: pmToBlocks(doc.content) }
 }
+
+// docstream writes inline images as `<img src alt />`; attachment chips read
+// better (and diff better) as plain markdown images.
+const ATTACHMENT_IMG = /<img src="(attachment:[^"\s]+)"(?: alt="([^"]*)")? \/>/g
+
+/**
+ * Serialize an editor AST to GitBook markdown, writing attachment chips as
+ * `![name](attachment:<id>)`. Use this instead of `serializeMarkdown` for
+ * editor output.
+ */
+export function serializeEditorMarkdown(doc: DocumentNode): string {
+  return serializeMarkdown(doc).replace(ATTACHMENT_IMG, (img: string, src: string, alt = "") =>
+    // `]` can't be escaped in `![alt]`; such names keep the <img> form.
+    alt.includes("]") ? img : `![${alt}](${src})`
+  )
+}

package/src/editor/nodes.tsx

@@ -32,6 +32,7 @@ import { ReplayPreview, isReplayQaUrl } from "@brett_lamy/docstream/replay"
 import { VideoEmbed } from "@brett_lamy/docstream/video"
 import { SourceFileEditor } from "./SourceFileEditor"
 import { useEditorRuntime } from "./runtime"
+import { GbAttachment } from "./attachments"
 
 function useDebouncedValue<T>(value: T, delay = 350): T {
   const [debounced, setDebounced] = useState(value)
@@ -983,4 +984,5 @@ export const gitbookNodes = [
   GbOpenapi,
   GbInlineImage,
   GbReference,
+  GbAttachment,
 ]

package/src/editor/runtime.tsx

@@ -1,6 +1,7 @@
 import { createContext, useContext, type ReactNode } from "react"
 
 import type { SourceFileSnapshot, SourceReferenceClient } from "@brett_lamy/docstream/source"
+import type { EditorAttachment } from "./attachments"
 
 export interface EditorRuntimeOptions {
   sourceClient?: SourceReferenceClient
@@ -8,6 +9,8 @@ export interface EditorRuntimeOptions {
   sourceAutoSave?: boolean | number
   onSourceSaved?: (snapshot: SourceFileSnapshot) => void
   onSourceError?: (error: Error) => void
+  attachments?: EditorAttachment[]
+  onAttachmentOpen?: (attachment: EditorAttachment) => void
 }
 
 const EditorRuntimeContext = createContext<EditorRuntimeOptions>({})

package/src/index.ts

@@ -1,6 +1,6 @@
 export { GitbookEditor } from "./editor/Editor"
-export type { GitbookEditorProps } from "./editor/Editor"
-export { astToTiptap, tiptapToAst } from "./editor/convert"
+export type { GitbookEditorProps, EditorAttachment } from "./editor/Editor"
+export { astToTiptap, tiptapToAst, serializeEditorMarkdown } from "./editor/convert"
 export type { PMNode } from "./editor/convert"
 
 // Building blocks for composing a custom editor (e.g. with Yjs collaboration
@@ -8,6 +8,7 @@ export type { PMNode } from "./editor/convert"
 export { createGitbookExtensions, getGitbookSchema, GbTable } from "./editor/extensions"
 export type { GitbookExtensionOptions, ReferenceSources } from "./editor/extensions"
 export { gitbookNodes, GbCodeBlock, GbReference } from "./editor/nodes"
+export { GbAttachment, formatBytes } from "./editor/attachments"
 export { SlashMenu, createSlashMenu, SLASH_ITEMS } from "./editor/slash-menu"
 export type { SlashItem } from "./editor/slash-menu"
 export { createReferenceSuggestion, resolveReferenceOptions } from "./editor/reference-menu"

package/src/styles.css

@@ -583,14 +583,15 @@
 }
 .gb-code > pre code { background: none; padding: 0; font-size: inherit; color: inherit; }
 /* gpu-lexer span classes (palette shared with docstream's HighlightedCode). */
-.gb-code .gb-syntax-comment { color: #6b6b78; font-style: italic; }
-.gb-code .gb-syntax-string { color: #a5d6a7; }
-.gb-code .gb-syntax-number { color: #f78c6c; }
-.gb-code .gb-syntax-keyword { color: #c792ea; }
-.gb-code .gb-syntax-type { color: #ffcb6b; }
-.gb-code .gb-syntax-function { color: #82aaff; }
-.gb-code .gb-syntax-constant { color: #f07178; }
-.gb-code .gb-syntax-operator { color: #89ddff; }
+/* Same palette and custom properties as Docstream's .docs-tok-*: follows the host color-scheme. */
+.gb-code .gb-syntax-comment { color: var(--docs-tok-comment, light-dark(#6E6E7A, #8A8A98)); font-style: italic; }
+.gb-code .gb-syntax-string { color: var(--docs-tok-string, light-dark(#23803A, #A5D6A7)); }
+.gb-code .gb-syntax-number { color: var(--docs-tok-number, light-dark(#C2410C, #F78C6C)); }
+.gb-code .gb-syntax-keyword { color: var(--docs-tok-keyword, light-dark(#8839C4, #C792EA)); }
+.gb-code .gb-syntax-type { color: var(--docs-tok-type, light-dark(#A15C00, #FFCB6B)); }
+.gb-code .gb-syntax-function { color: var(--docs-tok-function, light-dark(#2F5BD3, #82AAFF)); }
+.gb-code .gb-syntax-constant { color: var(--docs-tok-constant, light-dark(#C8283F, #F07178)); }
+.gb-code .gb-syntax-operator { color: var(--docs-tok-operator, light-dark(#0B7285, #89DDFF)); }
 
 /* ── Updates / changelog (mirrors .docs-updates) ────────── */
 .gb-updates { margin: 0.85em 0; border-top: 1px solid var(--gb-border); }
@@ -859,3 +860,163 @@
   outline: 2px solid var(--gb-primary);
   outline-offset: 1px;
 }
+
+/* ---- Attachment chips (pasted images in imagePaste="chip" mode) ---- */
+
+.gb-attachment-wrap {
+  display: inline;
+}
+
+.gb-attachment {
+  display: inline-flex;
+  align-items: center;
+  gap: 5px;
+  max-width: 100%;
+  padding: 1px 7px 1px 3px;
+  border: 1px solid var(--gb-border);
+  border-radius: 7px;
+  background: var(--gb-muted);
+  color: var(--gb-text);
+  font-size: 0.85em;
+  line-height: 1.5;
+  vertical-align: middle;
+  cursor: pointer;
+  user-select: none;
+  transition: border-color 120ms ease, background-color 120ms ease;
+}
+.gb-attachment:hover {
+  border-color: var(--gb-muted-foreground);
+}
+.gb-attachment:focus {
+  outline: none;
+}
+.gb-attachment:focus-visible,
+.ProseMirror-selectednode .gb-attachment {
+  outline: 2px solid var(--gb-primary);
+  outline-offset: 1px;
+}
+
+.gb-attachment-thumb {
+  display: inline-flex;
+  flex-shrink: 0;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 16px;
+  overflow: hidden;
+  border-radius: 3px;
+  background: var(--gb-border);
+  color: var(--gb-muted-foreground);
+}
+.gb-attachment-thumb img {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}
+.gb-attachment-thumb-icon {
+  width: 12px;
+  height: 12px;
+}
+
+.gb-attachment-name {
+  overflow: hidden;
+  font-weight: 500;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+  max-width: 22ch;
+}
+.gb-attachment-size {
+  flex-shrink: 0;
+  color: var(--gb-muted-foreground);
+  font-variant-numeric: tabular-nums;
+  white-space: nowrap;
+}
+
+/* Portaled to <body>, outside .gb — tokens resolve from the host directly. */
+.gb-attachment-card {
+  position: fixed;
+  z-index: 1000;
+  box-sizing: border-box;
+  max-width: calc(100vw - 16px);
+  padding: 6px;
+  border: 1px solid var(--border, #e5e7eb);
+  border-radius: 12px;
+  background: var(--card, #ffffff);
+  color: var(--card-foreground, var(--foreground, #111827));
+  font-family: var(--font-sans, ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif);
+  box-shadow: 0 12px 32px rgba(0, 0, 0, 0.18), 0 2px 6px rgba(0, 0, 0, 0.08);
+  pointer-events: none;
+  animation: gb-attachment-in 120ms ease-out;
+}
+.gb-attachment-card-img {
+  display: block;
+  max-width: 360px;
+  max-height: 280px;
+  width: auto;
+  height: auto;
+  object-fit: contain;
+  border-radius: 7px;
+  background: var(--muted, #f4f4f5);
+}
+.gb-attachment-card-empty {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 160px;
+  height: 100px;
+  border-radius: 7px;
+  background: var(--muted, #f4f4f5);
+  color: var(--muted-foreground, #6b7280);
+}
+.gb-attachment-card-meta {
+  max-width: 360px;
+  padding: 6px 4px 1px;
+  overflow: hidden;
+  font-size: 12px;
+  line-height: 1.4;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+.gb-attachment-card-name { font-weight: 500; }
+.gb-attachment-card-size { color: var(--muted-foreground, #6b7280); }
+
+.gb-attachment-viewer {
+  position: fixed;
+  inset: 0;
+  z-index: 1001;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(0, 0, 0, 0.72);
+  cursor: zoom-out;
+  animation: gb-attachment-fade 140ms ease-out;
+}
+.gb-attachment-viewer-img {
+  max-width: 90vw;
+  max-height: 90vh;
+  object-fit: contain;
+  border-radius: 8px;
+  box-shadow: 0 24px 64px rgba(0, 0, 0, 0.45);
+}
+.gb-attachment-viewer-empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 10px;
+  color: #ffffff;
+  font-size: 14px;
+}
+
+@keyframes gb-attachment-in {
+  from { opacity: 0; transform: translateY(2px); }
+  to { opacity: 1; transform: none; }
+}
+@keyframes gb-attachment-fade {
+  from { opacity: 0; }
+  to { opacity: 1; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .gb-attachment-card,
+  .gb-attachment-viewer { animation: none; }
+}